Software 2000

home *** CD-ROM | disk | FTP | other *** search

/ Software 2000 / Software 2000 Volume 1 (Disc 1 of 2).iso / aga / aga137.dms / in.adf / Processors / Workbench / IFFMaster.Doc < prev next >

Wrap

Text File | 1990-10-24 | 27.0 KB | 590 lines

Documentation file for IFFMaster by JUNIX of ARCANE This documentation is for version 1.0 IFFMaster ver. 1.0 is the latest version of IFFMaster, and any references throughout the text to "IFFMaster" or "the program" are all references to this version. DOCUMENTATION OVERVIEW: SECTION 1: Introduction to IFFMaster SECTION 2: IFFMaster overview 2.1: Basic Terms 2.2: The Workscreen 2.3: The Mouse 2.4: The Menus 2.5: The Preferences Window SECTION 3: Using IFFMaster 3.1: Loading A Picture 3.2: Saving Data 3.3: The keyboard 3.4: Brush 3.5: Palette APPENDIX A: IFFMaster Version & Development History Small print at bottom of contract: This program is entirely Public Domain - Its use is entirely at your own risk - I can, but will not salvage your disks after you've fucked them up. I am not a magician (at longer distances, anyway) and you gotta clean up your own messes. I don't care if IFFMaster causes any of you any trouble at all. Got it? SECTION 1: Introduction to IFFMaster IFFMaster is an IFF ILBM utility. It is able to load and save IFF ILBM and Raw format pictures. It is able to save the palette as binary or source file. It is able to save in sprite format (binary or as a source file). Then of course, as the only IFF converter I've seen to date, IFFMaster includes a palette, ability to select planes and resolution, HAM or XHALFBRITE modes features etc. etc. And surely you can load and save images of sizes up to 1024x1024 pixels, the maximum defined by the Amiga System (and the blitter). This is for now, Kickstart 1.3 and library version 34. In the future, when the new blitter (ECS - Extended Chip Set) becomes the standard, the system will permit larger blits and then larger bitmaps will be possible, and IFFMaster will be updated to support this. You are naturally not limited to saving images of the same size as the loaded one - with the brush feature you can save pictures of any size you could possibly want... A C K N O W L E D G E M E N T S I would like to thank: · Amanda, for calling on me when I was ill · the rest of ARCANE, for their support and help with this project (I'm afraid I'm not very useful to the group these days, anyway) · Mike of ARCANE (in particular), for the technical discussions · my dog, for pouring tea all over my disks · my other dog, for biting my fingers whenever possible · Dirty Harry Callahan, for providing entertainment (Go ahead, make my day!) · The Coca-Cola Company, for that strange dark acid · Electronic Arts, for EA IFF 85 · Commodore-Amiga, for the Amiga · the ones I've already forgotten, for everything! If any C freaks out there want to contact me, just talk to any member af ARCANE and ask for JUNIX, the crazy C programmer (me). Then I'll get in touch with you ASAP. SECTION 2: IFFMaster Overview 2.1: Basic Terms : 2.1.1: IFF ILBM Files: IFF means »Interchange File Format« and the story of IFF began back in 1985 back in good old U.S. of A. when Electronic Arts introduced IFF to Commodore-Amiga. At CMB-Amiga everybody seemed to like the idea, and this was the beginning af "EA IFF 85", the standard itself. At that point IFF included ILBM (the picture format: InterLeaved Bit Map), SMUS (Simple MUsical Score), 8SVX (8-bit Sampled Voice/VoX) and FTXT (Formatted TeXT). This was the "core" of IFF. The IFF standard, I might add, was revised in some ways in november 1988 - some new registered FORMs and chunks was introduced. An IFF file consists of a group of chunks. A group is either a FORM, a LIST or a CAT. The ILBM is a form, although a FORM might appear in a LIST or a CAT (actually DeluxeVideo saved the movie in a CAT (concatenation) of FORM ILBMs). The ILBM FORM consists of a number of chunks: · BMHD BitMap HeaDer - main info structure · CMAP Color MAP - the palette · GRAB GRABbed point - an (x,y) offset form the mouse (brush handle) · DEST DESTination - used for merging few planes into a large bitmap · SPRT Sprite PRioriTy - sprite priority · CAMG Commodore-AMiGa - Amiga display modes (HIRES,LACE,HAM etc.) · CRNG Color RaNGe - cycling info (DeluxePaint) · CCRT Color Cycling Range & Timing - cycling info (Graphicraft) · BODY bitmap BODY - contains all bitmap and masking data (possibly compressed) (Not complete) Of all these chunk types only BMHD and BODY are needed. (That is not quite true, 'cuz an ILBM with no planes and a CMAP is the proper way to save a palette - then a BODY chunk is not needed.) The IFF ILBM is stored in standard AmigaDOS files, often referred to as pictures, images or ILBMs. It is in that shape (the file) the user of IFFMaster will use the ILBM file. 2.1.2: Raw data: As a contrast to the very portable ILBM files (even the PC/MS DOS of DeluxePaint uses the ILBM standard) is the raw data file. The raw data file is simply the planes dumped to disk one by one. These raw files (as they will be referred to) are normally bigger than the corresponding ILBM file (in spite of the IFF overhead waste structures), as raw files are not compressed (ILBMs are normally compressed by the ByteRun compression technique). A raw file will be garbage to anyone who doesn't know it's width, height and number of planes, as these values are not stored in the file. Also the palette CAN BE out in the thin air, as it is stored quite incognito in the beginning or at the end of the file, if stored at all. However, in spite of all the disadvantages of the raw file (or raw format, as it is also called at times), there is one MAJOR advantage. The raw file is ready for direct inclusion in programs, as the »bare« raw format is the same format as the one the SCREEN-DMA (DMA=Direct Memory Access) uses, meaning that the raw file is 100% ready to splashed out to the screen. 2.1.3: AmigaDOS File: An AmigaDOS file is a collection of bytes managed by the AmigaDOS operating system, referred to by a file name, such as DF1:Source/myprog.c Where "DF1:" is the device name (allways followed by a colon), "Source/" is the drawer or directory specification. "myprog.c" is the actual name of the file. (Some people often makes a destinction between "myprog" and ".c". Anything after a period is normally called a file extension. This is mainly a remainder from MS/PC-DOS where all files MUST have an extension of 3 characters) If all this is new to you you should either : · 1 : Buy yourself a ZX-81 · 2 : Study "The AmigaDOS Manual" (Bantam Computer Books) · 3 : Go fuck yourself (as in suggestion 1) 2.2: The Workscreen: When the IFFMaster program is started off and running, that is, if IFFMaster could allocate the memory for the screen, the window and the fast-text routines, it opens a customscreen with the title "IFFMaster vx.x by JUNIX / »ARCANE!«" (or the like). If the machine has recognized the PAL mode, IFFMaster will sense this and use the PAL screen sizes. Under the title bar, the status-line is placed. It displays information about: · Screen Mode and number of bitplanes: An 'M' denotes "Modes" then a number (1-6), the number of planes. Then a symbol: Either h for HIRES, ½ for EXTRA_HALFBRITE or a capital H for HAM (Hold And Modify). After this mode symbol the "interlace active" symbol is shown. If interlace is active, a capital I, for interLACE, is displayed. (Please note that HAM and EXTRA_HALFBRITE are only available when using six bitplanes, and that HIRES is not allowed with more than four bitplanes - 16 colors total) · Brush information: The values shown depend on what's happening. If you havent selcted a brush yet, nothing is displayed. If, however, you are selecting the brush size or have selected it, the field will show the size of the brush. If you have fixed the brush-size, however, you will see the fixed size, even before you have selcted the position. This information is shown in the form bWxxx bHxxx, for brushWidth and brushHeight, respectively. xxx represents the number. · Width and height information for the entire image: You are at all times able to to see the width and height of the entire image. This information is displayed in the form Wxxx Hxxx, for the Width and Height of the image, respectively. xxx represents the number. · Mouse X and Y coordinates: At the rightmost positions of the status line, you are able to see the X- and Y-axis coordinates of the mouse, relative to (0,0) at the leftmost, and topmost position of the image. If the image is scrolled, the coordinates follow (0,0), so that you allways have the correct figures. These X and Y numbers are updated every time you move the mouse, and becomes incorrect when you distract the program (e.g) use the mouse for menu-selection. To account for this, just move the mouse - as soon as you move the mouse the program notes the new position and prints it. These numbers are shown in the form Xxxx Yxxx, which should be self explanatory. Of course, xxx represents the number. · Ruler: (if selected in preferences) The ruler helps you in your orientation around the loaded image. Every square is 8x8 pixels, and two of these squares are then 16 pixels - a magic number on most occations. This can be toggled on/off by the preferences screen - the default is off. Having these things put right, you should be able to understand the following subsections of the IFFMaster overview. 2.3: The Mouse: In IFFMaster, the mouse serves the duty of brush and menu selection. Additionally, you might want to use the mouse for checking that images are the way you want them to be - when that little dot should be in line with this little dot, etc. etc. As explained above, the coordinates at the of the screen are updated when you move the mouse. The mouse is used for brush-pickups, and you can clear the brush with the mouse: Hold the left button down, click the right (menu) button, and then release the left mouse button again. This will clear the brush, and prepare the program for picking another one up. 2.4: The Menus: The menus are set up like this: Project ToolBox Load Brush Save picture as raw Fix brush size as IFF Un-fix brush Save brush as raw Palette as IFF Convert ANIM file »NOT AVAILABLE« Save sprite in 4 colors Save picture windows »NOT AVAILABLE« in 16 colors Open new CLI Append raw (GHOSTED AT START) Generate palette Process batch »NOT AVAILABLE« Save brush mask Preferences Save picture mask About Quit IFFMaster Note 1: The items marked »NOT AVAILABLE« are only appetizers - they will be included is a later version of IFFMaster. If you have any other suggestions, please contact me. When the menus are used, a menu-palette is loaded into the hardware. This way the menu-entries display correctly in all modes - even HAM... This changing of colors will (sometimes) make the display flash. THIS IS NOT A FAULT, just a necessity! And if you have loaded a picture, the colors appearing when you press the right mouse button will be very *interesting*. Try it out! (Prepare for a mental check afterwards - ACIIIIID!) 2.5: The Preferences Window: The preferences window will provide the options not given other places in the program (rulers on/off, save sprite mode, etc). At startup the configuration file "S:IFFMaster.prefs" is loaded (if located). This 24 bytes long file will contain the IFFMaster preferences. To use the preferences, select Project Preferences (or right-Amiga P), and click any of the items you see. You can, of course, press the key just left of the item you want instead. Here are the options in you can alter: Rulers: Hidden or shown - self explanatory * Bitplanes save method: Normal/Raster save - see note 1 Palette information: Not used/Behind picture/Before picture - see note 2 Separate palette save: Binary data/ASM source/ASM source for copper-list Sprites save method: Binary data/ASM source files Sprite control words: Not used/Used - the hardware sprite words * Extra blitter words: Not used/Left of picture/Right of picture - for bobs Brush pickup: One click/Two clicks - a good solution for bad mice * IFF ILBM compression: None/Byte Run 1 Algorithm - decide for yourself And the three commands: Cancel preferences - quit the prefs while discarding the changes Use these prefs - leave and use the new settings (same as the closegadget) Save and use prefs - leave prefs, use and SAVE prefs. * is used to indicate that the option only applies to files written from IFFMaster. When reading, these options are ignored. Note 1: Raster save is when the planes are interleaved; (example with 3 bitplanes): 1st line from plane1, then 1st line from plane2, then 1st line from plane3, then 2nd line from plane1, then 2nd line from plane2, then 2nd line from plane3, then 3rd line from plane1, and so forth. Note 2: This is the position of the palette data. If saved within the raw file, it is possible to load the image back into IFFMaster with the correct colors. As this will not be important to very many people, I've chosen to pick "Not used" as the preference. SECTION 3: Using IFFMaster 3.1: Loading A Picture: When you select Project Load picture (Right-Amiga L) the file requester opens, prompting you for a file to load. Now select the file, and press the "Load!" gadget. Then IFFMaster will try to load the picture file into the Amiga's memory. If the file is an IFF ILBM file, it will load automatically. If - however - the file is not an IFF ILBM file, IFFMaster assumes the file to be a raw dump of a picture. The program will then ask the user (that's you!) how wide and tall the file is and how many bytes IFFMaster should skip at the beginning of the file (if needed, leave empty if not). Then, after pressing <RETURN> after this last number (use decimal numbers), you have to press one of the keys 1-7 to decide how many bit-planes the picture's got. If you press '6' IFFMaster will load the picture as an EXTRA_HALFBRITE picture (6 planes and 32 palette entries). If you press '7' IFFMaster will load the picture as a HAM picture (6 planes but only 16 palette entries). If, however, you press the space bar, the cursor will re-appear at the width box, leaving you to alter the numbers entered (this is handy because you don'r have to use the mouse). When you have selected the width, height, offset (if needed) and number of bitplanes, just press <RETURN> (or press Load gadget) to confirm the inputs and load, or <ESC> (or press Abandon gadget) to drop out. If you choose to load the picture, IFFMaster will get the memory the image would fit (memory is allocated dynamically = at load time) and commence the load. If any errors occur IFFMaster will inform you, and the load will be cancelled. If you have loaded a raw picture with a palette (specify this in the preferences) and the colors are all equal (typically black) press the <HELP> key. This will give you the standard (DPaint III) palette. This litte trick works, needless to say, at all times. 3.2: Saving Data : When you feel like saving some data, you'll have to consider these two things: · What to save (brush/entire image) · How the data should be saved (IFF, raw or as a sprite, mask) Of course, you'll know this all by yourself before you load IFFMaster. For full pictures, there's no problems - you simply load them, and then save them again. I recommend that you only use brush mode if you really need it real bad. If, for instance, you have an ILBM with a little graphical item in it and you want to take it out for use within your own program, the normal procedure is to load the picture into DPaint and cut out the brush there and then load this IFF brush into IFFMaster and finally save it to a raw file. But, if you don't have DPaint (e.g on an island in the Pacific Ocean) or think it would be a waste of time to load it, just for the sake of that little stupid brush - use IFFMaster. First, load the picture. Then cut out the brush you want to save (for a discussion of the brush feature, see subsection 3.4). Now save the brush using the Project Save Brush command. Simple as that. Got it? When you have loaded the image (and cut a brush out if that's what you desire), it's saving time. It is most likely that you save as a raw file, if you want to use the image in a demo or an application program. If you save it as a raw file you are able to use the image with the copper or the blitter, without any decompression or translation (which is essential with IFF ILBMs). For the first two categories, IFF ILBM and raw file, the image is saved with the attributes of the IFFMaster screen. The number of bitplanes (1-6) used is based ONLY upon the number of planes selected within the program at saving time, and NOT the number of planes loaded. The other screen attributes are not REALLY interesting, only you should not save an ILBM in HAM mode, unless you really mean it. A raw image will not load into DPaint, while an EXTRA_HALFBRITE (also 6 bitplanes) will (in DPaint III, that is). The width and height of the saved output depends on the brush size (for brushes) or the size of the entire image (for whole pictures). However, the width of the image saved to raw files is allways rounded up to the nearest higher multiply of 16 (pixels), which is a processor word. For IFF saved output, you need not bother about rounding off, only note that only some very few chunk types are written out to the file, namely BMHD(BitMapHeaDer), CMAP(ColorMAP), CAMG(Commodore-AMiGa display modes) and BODY (the picture "body" - the bitmap itself). The picture will be saved without masking (mskNone). If you load an ILBM with cycling, GRAB information etc. and save this back again, you lose these informations. But - why on earth use this converter program to load AND save ILBMs? The Project Append (right Amiga-'M') is used when you have to put a large number of graphical objects (source codes or binary data) together in one file. Firstly, save the first object in the file where you want all your data to go. Then select the next object and use the Append command. This will put the data at the end of the original file. This is very useful in conjunction with the fix brush size facility. Please note that you can NOT append ILBM files on to one another. Only raw format output is appendable. 3.3: The Keyboard : When using IFFMaster the keyboard is used for many various things: Enterings text or numbers, in the File Requester or the Load raw file function, or at the preferences window. * Scrolling around in the bitmap (the image). Use the cursor keys for this. If you use the cursor key alone, the scrolling speed is 4 pixels. However, if you press an ALT key while scrolling the speed will be higher, 16 pixels, to be exact. And if you use a SHIFT key whilst scrolling, the speed will be very slow, only one pixel per keystroke or repeat impulse. Use the CTRL key to move to the edge of the bitmap (the image): Press CTRL-CursorLeft to move to the leftmost position, CTRL-CursorLeft to go to the bottommost, etc. etc. * Selecting the screen depth (number of bitplanes, and colors). Press the keys 1-6 for this. The number of colors are equal to 2^<number of bit-planes>. Thus a depth of one equald 2 colors, 2 bitplanes are 4 colors, and 3 bitplanes gives you 8 colors, and so forth. 6 bitplanes is a special case, though. If you select this (or load a picture with this setting), you'll get either 64 colors (EXTRA_HALFBRITE) or the special Hold-And-Modify (HAM) mode. For description of these modes, see the official Amiga Hardware Reference Manual. Please note that you cannot use the numbers on the keypad for this. If you have loaded a picture in, say 4 bitplanes, and want to cut off some of these, please note that IFFMaster will just chop off the high order (MSB) planes. It doesn't actually inspect the picture to check its colors. To use less colors (remove the least used ones) please turn to PixMate, which is written for that purpose. * Setting the screen mode. Use the following keys: The 'I' key is used to toggle INTERLACE mode. This doubles the vertical (Y) resulution. The 'H' key will, in case you do not use more than 4 bitplanes, toggle HIRES mode. This will double the horizontal (X) resolution The 'A' key will (in 6 bitplane mode only) turn on HAM, if it's not already active. The 'E' key will (in 6 bitplane mode only) turn on EXTRA_HALFBRITE, if it's not already active. * Use the HELP key (unshifted) to reset the palette to a standard, high-contrast DPaint III palette. * Use shift-HELP to show information about the program... * Use the SPACE BAR instead of the left mouse button when selecting brushes. * Use the keyboard to select some of the menu-items. 3.4: Brush : To select a brush, use the brush menu item, ToolBox Brush, or press 'b' (non-shifted). This will clear the brush currently selected and the brush will be ready for pickup. First, move to the first corner of the brush you want to pick up. Now press the left mouse button(do not release it if you haven't selected "Brush Pickup: Two click method") or press the SPACE BAR. Then move to the opposite corner. If you have selected "Brush Pickup: Two click method" in the preferences, you have to click the left mouse button or press the SPACE BAR again. However, if this option is NOT active, just release the left mouse button. While selecting the brush, the width and height of the brush will be displayed in the menu-bar. If you have to save a number of brushes of the the same size (e.g. sprites) you may prefer the "Fix brush size"-facility. To fix the brush size, select ToolBox Fix brush size or press 'f' (unshifted). Then proceed the same way as above (the normal brush selection). Then, when the size is fixed, use the 'b' key (or the corresponding menu item) to clear the old brush. Now, when the brush size if fixed, use the fixed brush as the normal one. Only, when you select the location, it has to be in the upper left corner. The size will be displayed while moving around. When you have reached the right spot, press SPACE BAR or click the left mouse button. You can clear the old brush in a very simple way: Hold the left button down, click the right (menu) button, and then release the left mouse button again. Then the brush is cleared. 3.5: Palette : Use the palette to change to colors. When inside the palette, use the three proportional gadgets to adjust the Red, Green and Blue portions of the color, or (in HSL mode) the Hue, Saturation or Luminance of the color. To copy a color, select the first color, click the COLOR-gadget, and then select the second color. To spread the colors, click the range gadget, select the first color, then the second, and the colors will be spread inbetween these two colors. To leave the palette subsection, use the OK-gadget to accept the changes, or the CANCEL to abandon any modifications. APPENDIX A: IFFMaster Version & Development History: Program history: -------------------------------------------------------------------------- 10-11-89 Created this file for the good of ARCANE! 12-11-89 Put in palette! Began scrolling. 13-11-89 Joke!, Planes and Modes ok!, colors and menus ok, etc. Fixed the mouse-movement, too (no waiting!) 14-11-89 Coordinates, W,H Modes displayed correctly. Mem usage! 15-11-89 Decided to semi-drop the original IFF stuff and do it myself! 16-11-89 Joined with IFF reader routines. It Works (a bit)... ... IFF read works 100%. Write raw works. 19-11-89 Wrote some of the documentation 21-11-89 Preferences meditation. Found an ok solution 22-11-89 Prefs programming + error window 23-11-89 Further pref coding 04-12-89 I find "Family Ties" repulsive and jukky! 06-12-89 LNP - Late Night Programming - ScrollXY OK! 09-12-89 Changed ScrollXY to use only one blit/Brush features 10-12-89 It's debugging time! Got it! 11-12-89 programming overnight - feeling fine! 13-12-89 raw load... 16-12-89 Amanda and I together for half a year! 17-12-89 ILBM Save fixed ysterday - today: LButton+RButton=bress_b 19-12-89 Fix I/O (saved 200 bytes). Startup text. Pointer. MENUVERIFY 25-12-89 Did Mask routines - fixed pr_WindowPtr things and colors 26-12-89 Happy BirthDay N - Amanda home in 4 days - SavePic modes ... Coding overnight - Docs and append. Mabye sprites and Palette ... (coding overnight to provide Mike+Merlin with a pre-release) 01-90 Chopped off some bytes and added some more 18-01-90 Sprites... 21-01-90 Added INTERNAL VERSION... 22-01-90 Fixed the last peculiarities, linked and crunched the release version 25-01-90 Fixed the DOCument -------------------------------------------------------------------------- Version history: IFFMaster version 0.5 (pre-release 1): This version is not complete There is no Append/Erase function. The "Save picture windows", "Convert ANIM file" and "Process Batch" smart-ass routines are not even thought of... Finally, the documentation is not complete... IFFMaster version 1.0 (real release): A lot of things put right. This version is smaller, it has PAL support, it doesn't use as much chipmem on fastmem machines as the old one did, it is now a fucking suave program. Finally, the documentation has been fixed! All in all, this is well - er... for now, anyway - complete! <End of file>